[Proof of concept] Customize Furo to use Qiskit branding #233
+390
−37
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Eric-Arellano
force-pushed
the
furo-via-conf-py
branch
from
e1e4359 to
3d23c98
Compare
Eric-Arellano
force-pushed
the
furo-via-conf-py
branch
from
3d23c98 to
f82c97d
Compare
|
Closing in favor of #269, which restructures this code so that we can actually safely land the Furo theme. |
Eric-Arellano
added a commit
that referenced
this pull request
Apr 14, 2023
We plan to land the Furo proof of concept soon (#233), so that people can more easily finish Qiskit-ifying the theme. We have to set slightly different conf.py values, like `html_theme_options`. We'll do that by something like this: ```python if "FURO" in os.environ: # furo options else: # pytorch options ``` So, this is prework to make `conf.py` as simple as possible before adding new complexity. -- This also removes the unnecessary `.. contents::` directives from some pages. They didn't actually do anything, but cause a huge warning when using Furo. With Pytorch, we still have our right page-level table of contents even without it.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Seeing if we can satisfy #232 by using Furo's builtin customization rather than vendoring the theme and modifying the original source code. That will likely be much easier for us to maintain. For example, no need to have infrastructure that uses Node.js to compile the Sass files.
We will need to solve pradyunsg/furo#204 still because we can't expect everyone to put this code in their conf.py and templates folder. We need to pre-set this all and distribute it as our own custom theme.
Customization requirements
Color scheme
We can customize any of Furo's Sass variables via
html_theme_options. See https://github.com/pradyunsg/furo/blob/main/src/furo/assets/styles/variables/_colors.scss. For example, we set the color here to Qiskit purple:We can also set whatever CSS rules we want in
custom.css.TODO:
Fonts
This is set via
html_theme_options, for both the normal font and monospace font. We load the font via Google Fonts loaded in the header.Top nav bar
We extend
base.htmlto load our web components, then changepage.htmlto render the nav bar at the top of the page.--
TODO:
Footer & analysis code
We extend
base.htmlto add our analytics code, then change the footerpage.htmlto include our "Was this page helpful?" question. We use Furo'snext pageand copyright code, but could use our own if we wanted.TODO:
<hr>render? It's in the DOM.Side bar: languages and versions
This works by adding custom side bar elements, set in
conf.py. While it does not yet have any styling, we can add that in a follow up. The basic proof of concept works and e.g. clicking on the elements works.TODO:
sidebar_hide_name=True